<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>apply manual page - Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> apply</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<H3><A NAME="M2">NAME</A></H3>
apply &mdash; Apply an anonymous function
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>apply </B><I>func</I> ?<I>arg1 arg2 ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
The command <B>apply</B> applies the function <I>func</I> to the arguments
<I>arg1 arg2 ...</I> and returns the result.
<P>
The function <I>func</I> is a two element list <I>{args body}</I> or a three
element list <I>{args body namespace}</I> (as if the
<B><A HREF="../TclCmd/list.htm">list</A></B> command had been used).
The first element <I>args</I> specifies the formal arguments to
<I>func</I>. The specification of the formal arguments <I>args</I>
is shared with the <B><A HREF="../TclCmd/proc.htm">proc</A></B> command, and is described in detail in the
corresponding manual page.
<P>
The contents of <I>body</I> are executed by the Tcl interpreter
after the local variables corresponding to the formal arguments are given
the values of the actual parameters <I>arg1 arg2 ...</I>.
When <I>body</I> is being executed, variable names normally refer to
local variables, which are created automatically when referenced and
deleted when <B>apply</B> returns.  One local variable is automatically
created for each of the function's arguments.
Global variables can only be accessed by invoking
the <B><A HREF="../TclCmd/global.htm">global</A></B> command or the <B><A HREF="../TclCmd/upvar.htm">upvar</A></B> command.
Namespace variables can only be accessed by invoking
the <B><A HREF="../TclCmd/variable.htm">variable</A></B> command or the <B><A HREF="../TclCmd/upvar.htm">upvar</A></B> command.
<P>
The invocation of <B>apply</B> adds a call frame to Tcl's evaluation stack
(the stack of frames accessed via <B><A HREF="../TclCmd/uplevel.htm">uplevel</A></B>). The execution of <I>body</I>
proceeds in this call frame, in the namespace given by <I>namespace</I> or
in the global namespace if none was specified. If given, <I>namespace</I> is
interpreted relative to the global namespace even if its name does not start
with
&ldquo;::&rdquo;.
<P>
The semantics of <B>apply</B> can also be described by:
<P>
<PRE>proc apply {fun args} {
    set len [llength $fun]
    if {($len &lt; 2) || ($len &gt; 3)} {
         error &quot;can't interpret &#92;&quot;$fun&#92;&quot; as anonymous function&quot;
    }
    lassign $fun argList body ns
    set name ::$ns::[getGloballyUniqueName]
    set body0 {
         rename [lindex [info level 0] 0] {}
    }
    proc $name $argList ${body0}$body
    set code [catch {uplevel 1 $name $args} res opt]
    return -options $opt $res
}</PRE>
<H3><A NAME="M5">EXAMPLES</A></H3>
This shows how to make a simple general command that applies a transformation
to each element of a list.
<P>
<PRE>proc map {lambda list} {
    set result {}
    foreach item $list {
        lappend result [<B>apply</B> $lambda $item]
    }
    return $result
}
map {x {return [string length $x]:$x}} {a bb ccc dddd}
      <I><font size="+1">&rarr;</font> 1:a 2:bb 3:ccc 4:dddd</I>
map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4}
      <I><font size="+1">&rarr;</font> 2 -2 -4 -4 -2 2 8 16 26</I></PRE>
<P>
The <B>apply</B> command is also useful for defining callbacks for use in the
<B><A HREF="../TclCmd/trace.htm">trace</A></B> command:
<P>
<PRE>set vbl &quot;123abc&quot;
trace add variable vbl write {<B>apply</B> {{v1 v2 op} {
    upvar 1 $v1 v
    puts &quot;updated variable to &#92;&quot;$v&#92;&quot;&quot;
}}}
set vbl 123
set vbl abc</PRE>
<H3><A NAME="M6">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/proc.htm">proc</A></B>, <B><A HREF="../TclCmd/uplevel.htm">uplevel</A></B>
<H3><A NAME="M7">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#anonymous function">anonymous function</A>, <A href="../Keywords/A.htm#argument">argument</A>, <A href="../Keywords/L.htm#lambda">lambda</A>, <A href="../Keywords/P.htm#procedure">procedure</A>, <A href="../Keywords/.htm#"></A>
<div class="copy">Copyright &copy; 2006 Miguel Sofer
<BR>Copyright &copy; 2006 Donal K. Fellows
</div>
</BODY></HTML>
